<?php
/**
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * @author Eddie Drapkin <eddie@frameweld.com>
 * @license http://www.gnu.org/licenses/lgpl-3.0.txt
 * @package Solphr
 * @subpackage Request
 * @version 0.1-pre
 */

/**
 * The interface Solphr_Request_Interface will be implemented by a Solr_Request client for
 * internal use to manage the connection with Solr.
 *
 * @author Eddie Drapkin <eddie@frameweld.com>
 * @license http://www.gnu.org/licenses/lgpl-3.0.txt
 * @package Solphr
 * @subpackage Request
 */
interface Solphr_Request_Interface {
	/**
	 * Which class we're using as our implementation,
	 * used in several places.
	 */
	const IMPL = 'Solphr_Request_Curl';
	
	/**
	 * HTTP GET method.
	 */
	const GET = 0;
	
	/**
	 * HTTP POST method.
	 */
	const POST = 1;
	
	/**
	 * Special characters that need to be escaped in Lucene queries.
	 */
	const SPECIAL_CHARACTERS = '+ - && || ! ( ) { } [ ] ^ " ~ * ? :';
	
	/**
	 * Lucene's special characters' replacements.
	 */
	const SPECIAL_REPLACEMENTS = '\+ \- \&\& \|\| \! \( \) \{ \} \[ \] \^ \" \~ \* \? \:';
	
	/**
	 * Escapes a single "word" - anything, could be multiple words,
	 * that is not a search phrase, which are encapsulated in " ".
	 * @param string $query The "word" to be escaped.
	 * @return string The escaped word.
	 */
	static public function queryEscapeWord($query);
	
	/**
	 * Escapes an ENTIRE query, either something like 'foo+' or something as
	 * large as 'foo "bar baz" boom bang *' 
	 * @param string $query The user supplied query to be used.
	 * @return string The escaped query.
	 */
	static public function queryEscape($query);
	
	/**
	 * Utility function to ease creation of full URLs for Solr_Request::__construct().
	 * @param string $host The host Solr resides on, can be any valid hostname.
	 * @param string $port The port Solr is listening on.
	 * @param string $path The path of the index you which to search, something like '/solr/'.
	 * @return string The built URL.
	 */
	static public function buildUrl($host, $port, $path);
	
	/**
	 * Class constructor.
	 * @param string $URL The URL for Solr, something like http://foo.bar.com:12345/solr/ 
	 * @param int $method The HTTP method for use in this instance, one of the two GET/POST constants.
	 * @return null
	 */
	public function __construct($URL, $method);
	
	/**
	 * Pings the server to make sure that a connection can be established.
	 * @return bool Success of the ping.
	 */
	public function ping();
	
	/**
	 * (Re-)Sets the URL for the class, where Solr is.
	 * @param string $URL The URL for Solr, something like http://foo.bar.com:12345/solr/
	 * @return null
	 */
	public function setURL($URL);
	
	/**
	 * Set Data to be pushed to Solr from a PHP array.
	 * @param array $data The data to be pushed to Solr.
	 * @return null
	 */
	public function setDataFromArray(array $data);
	
	/**
	 * Sets Data to be pushed to Solr from a query-string formatted string.
	 * @param string $data The query string itself.
	 * @param string $escaped Whether the query string has been already escaped.  NOTE THAT THIS MEANS LUCENE ESCAPING AS WELL AS URLESCAPING.
	 * @return null
	 */
	public function setDataFromString($data, $escaped = false);
	
	/**
	 * Commits the current "transaction" and returns true/false.
	 */
	public function commit();
	
} 